<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>bdep-common-options(1) bdep 0.17.0</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : man.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 *
 */

#content
{
  max-width: 42.1em;
  padding-left: 1.5em; /* Reserve for the heading. */
}

h1
{
  font-weight: normal;
  font-size: 1.58em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.88em;
}

/* Definition list for options. */
dl.options dt {margin: 1em 0 0 0;}
dl.options dd {margin: .1em 0 0 4.5em;}

/* Make lists inside option descriptions a tad smaller. */
dl.options dd ul, dl.options dd ol, dl.options dd dl
{
  font-size: 0.889em;
  line-height: 1.4em;
}

  </style>

</head>
<body>
<div id="content">

  <h1>NAME</h1>

  <p><b><code>bdep-common-options</code></b> &#8211; details on common options</p>
  <h1>SYNOPSIS</h1>

  <p class="code"><code><b>bdep</b> [<i>common-options</i>] ...</code></p>

  <h1>DESCRIPTION</h1>

  <p>The common options control behavior that is common to all or most of the
  <code><b>bdep</b></code> commands. They can be specified either before the
  command or after, together with the command-specific options.</p>

  <h1>COMMON OPTIONS</h1>

  <dl class="options">
    <dt><code><b>-v</b></code></dt>
    <dd>Print essential underlying commands being executed. This is equivalent
    to <code><b>--verbose 2</b></code>.</dd>

    <dt><code><b>-V</b></code></dt>
    <dd>Print all underlying commands being executed. This is equivalent to
    <code><b>--verbose 3</b></code>.</dd>

    <dt><code><b>--quiet</b></code>|<code><b>-q</b></code></dt>
    <dd>Run quietly, only printing error messages. This is equivalent to
    <code><b>--verbose 0</b></code>.</dd>

    <dt><code><b>--verbose</b></code> <code><i>level</i></code></dt>
    <dd>Set the diagnostics verbosity to <code><i>level</i></code> between 0
    and 6. Level 0 disables any non-error messages while level 6 produces lots
    of information, with level 1 being the default. The following additional
    types of diagnostics are produced at each level:

    <ol>
    <li>High-level information messages.</li>

    <li>Essential underlying commands being executed.</li>

    <li>All underlying commands being executed.</li>

    <li>Information that could be helpful to the user.</li>

    <li>Information that could be helpful to the developer.</li>

    <li>Even more detailed information.</li>
    </ol></dd>

    <dt><code><b>--stdout-format</b></code> <code><i>format</i></code></dt>
    <dd>Representation format to use for printing to
    <code><b>stdout</b></code>. Valid values for this option are
    <code><b>lines</b></code> (default) and <code><b>json</b></code>. See the
    JSON OUTPUT section below for details on the <code><b>json</b></code>
    format.</dd>

    <dt><code><b>--jobs</b></code>|<code><b>-j</b></code> <code><i>num</i></code></dt>
    <dd>Number of jobs to perform in parallel. If this option is not specified
    or specified with the <code>0</code> value, then the number of available
    hardware threads is used. This option is also propagated when executing
    package manager commands such as <a
    href="../../bpkg/doc/bpkg-pkg-update.xhtml"><code><b>bpkg-pkg-update(1)</b></code></a>,
    <a
    href="../../bpkg/doc/bpkg-pkg-test.xhtml"><code><b>bpkg-pkg-test(1)</b></code></a>,
    etc., which in turn propagate it to the build system.</dd>

    <dt><code><b>--progress</b></code></dt>
    <dd>Display progress indicators for long-lasting operations, such as
    network transfers, building, etc. If printing to a terminal the progress
    is displayed by default for low verbosity levels. Use
    <code><b>--no-progress</b></code> to suppress.</dd>

    <dt><code><b>--no-progress</b></code></dt>
    <dd>Suppress progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--diag-color</b></code></dt>
    <dd>Use color in diagnostics. If printing to a terminal the color is used
    by default provided the terminal is not dumb. Use
    <code><b>--no-diag-color</b></code> to suppress.</dd>

    <dt><code><b>--no-diag-color</b></code></dt>
    <dd>Don't use color in diagnostics.</dd>

    <dt><code><b>--bpkg</b></code> <code><i>path</i></code></dt>
    <dd>The package manager program to be used for build configuration
    management. This should be the path to the <code><b>bpkg</b></code>
    executable. You can also specify additional options that should be passed
    to the package manager program with <code><b>--bpkg-option</b></code>.

    <p>If the package manager program is not explicitly specified, then
    <code><b>bdep</b></code> will by default use <code><b>bpkg</b></code> plus
    an executable suffix if one was specified when building
    <code><b>bdep</b></code>. So, for example, if <code><b>bdep</b></code>
    name was set to <code><b>bdep-1.0</b></code>, then it will look for
    <code><b>bpkg-1.0</b></code>.</p></dd>

    <dt><code><b>--bpkg-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the package manager program. See
    <code><b>--bpkg</b></code> for more information on the package manager
    program. Repeat this option to specify multiple package manager
    options.</dd>

    <dt><code><b>--build</b></code> <code><i>path</i></code></dt>
    <dd>The build program to be used to build packages. This should be the
    path to the build2 <code><b>b</b></code> executable. You can also specify
    additional options that should be passed to the build program with
    <code><b>--build-option</b></code>.

    <p>If the build program is not explicitly specified, then
    <code><b>bdep</b></code> will by default use <code><b>b</b></code> plus an
    executable suffix if one was specified when building
    <code><b>bdep</b></code>. So, for example, if <code><b>bdep</b></code>
    name was set to <code><b>bdep-1.0</b></code>, then it will look for
    <code><b>b-1.0</b></code>.</p></dd>

    <dt><code><b>--build-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the build program. See
    <code><b>--build</b></code> for more information on the build program.
    Repeat this option to specify multiple build options.</dd>

    <dt><code><b>--curl</b></code> <code><i>path</i></code></dt>
    <dd>The curl program to be used for network operations. You can also
    specify additional options that should be passed to the curl program with
    <code><b>--curl-option</b></code>.

    <p>If the curl program is not explicitly specified, then
    <code><b>bdep</b></code> will use <code><b>curl</b></code> by default.
    Note that this program will also be used by the underlying
    <code><b>bpkg</b></code> invocations unless overridden.</p></dd>

    <dt><code><b>--curl-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the curl program. See
    <code><b>--curl</b></code> for more information on the curl program.
    Repeat this option to specify multiple curl options.

    <p>Note that these options will also be used by the underlying
    <code><b>bpkg</b></code> invocations provided that curl is used.</p></dd>

    <dt><code><b>--pager</b></code> <code><i>path</i></code></dt>
    <dd>The pager program to be used to show long text. Commonly used pager
    programs are <code><b>less</b></code> and <code><b>more</b></code>. You
    can also specify additional options that should be passed to the pager
    program with <code><b>--pager-option</b></code>. If an empty string is
    specified as the pager program, then no pager will be used. If the pager
    program is not explicitly specified, then <code><b>bdep</b></code> will
    try to use <code><b>less</b></code>. If it is not available, then no pager
    will be used.</dd>

    <dt><code><b>--pager-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the pager program. See
    <code><b>--pager</b></code> for more information on the pager program.
    Repeat this option to specify multiple pager options.</dd>

    <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt>
    <dd>Read additional options from <code><i>file</i></code>. Each option
    should appear on a separate line optionally followed by space or equal
    sign (<code><b>=</b></code>) and an option value. Empty lines and lines
    starting with <code><b>#</b></code> are ignored. Option values can be
    enclosed in double (<code><b>"</b></code>) or single
    (<code><b>'</b></code>) quotes to preserve leading and trailing
    whitespaces as well as to specify empty values. If the value itself
    contains trailing or leading quotes, enclose it with an extra pair of
    quotes, for example <code><b>'"x"'</b></code>. Non-leading and
    non-trailing quotes are interpreted as being part of the option value.

    <p>The semantics of providing options in a file is equivalent to providing
    the same set of options in the same order on the command line at the point
    where the <code><b>--options-file</b></code> option is specified except
    that the shell escaping and quoting is not required. Repeat this option to
    specify more than one options file.</p></dd>

    <dt><code><b>--default-options</b></code> <code><i>dir</i></code></dt>
    <dd>The directory to load additional default options files from.</dd>

    <dt><code><b>--no-default-options</b></code></dt>
    <dd>Don't load default options files.</dd>
  </dl>

  <h1>JSON OUTPUT</h1>

  <p>Commands that support the JSON output specify their formats as a
  serialized representation of a C++ <code><b>struct</b></code> or an array
  thereof. For example:</p>

  <pre>struct package
{
  string name;
};

struct configuration
{
  uint64_t         id;
  string           path;
  optional&lt;string> name;
  bool             default;
  vector&lt;package>  packages;
};</pre>

  <p>An example of the serialized JSON representation of
  <code><b>struct</b></code> <code><b>configuration</b></code>:</p>

  <pre>{
  "id": 1,
  "path": "/tmp/hello-gcc",
  "name": "gcc",
  "default": true,
  "packages": [
    {
      "name": "hello"
    }
  ]
}</pre>

  <p>This sections provides details on the overall properties of such formats
  and the semantics of the <code><b>struct</b></code> serialization.</p>

  <p>The order of members in a JSON object is fixed as specified in the
  corresponding <code><b>struct</b></code>. While new members may be added in
  the future (and should be ignored by older consumers), the semantics of the
  existing members (including whether the top-level entry is an object or
  array) may not change.</p>

  <p>An object member is required unless its type is
  <code><b>optional&lt;></b></code>, <code><b>bool</b></code>, or
  <code><b>vector&lt;></b></code> (array). For <code><b>bool</b></code>
  members absent means <code><b>false</b></code>. For
  <code><b>vector&lt;></b></code> members absent means empty. An empty
  top-level array is always present.</p>

  <p>For example, the following JSON text is a possible serialization of the
  above <code><b>struct</b></code> <code><b>configuration</b></code>:</p>

  <pre>{
  "id": 1,
  "path": "/tmp/hello-gcc"
}</pre>

  <h1>BUGS</h1>

  <p>Send bug reports to the
  <a href="mailto:users@build2.org">users@build2.org</a> mailing list.</p>

</div>

<div id="footer">
Copyright &#169; 2014-2024 the build2 authors.<br/>
Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.
</div>

</body>
</html>
